@material/checkbox

What is @material/checkbox?

@material/checkbox is a Material Design implementation of a checkbox component. It provides a customizable and accessible checkbox that can be used in web applications to allow users to make binary choices.

What are @material/checkbox's main functionalities?

Basic Checkbox

This code demonstrates how to initialize a basic Material Design checkbox using the @material/checkbox package.

import {MDCCheckbox} from '@material/checkbox';

const checkbox = new MDCCheckbox(document.querySelector('.mdc-checkbox'));

Indeterminate State

This code shows how to set a checkbox to an indeterminate state, which is useful for indicating a mixed selection.

import {MDCCheckbox} from '@material/checkbox';

const checkbox = new MDCCheckbox(document.querySelector('.mdc-checkbox'));
checkbox.indeterminate = true;

Handling Change Events

This code demonstrates how to listen for change events on the checkbox and handle them accordingly.

import {MDCCheckbox} from '@material/checkbox';

const checkbox = new MDCCheckbox(document.querySelector('.mdc-checkbox'));
checkbox.listen('change', () => {
  console.log('Checkbox state changed to: ', checkbox.checked);
});

Other packages similar to @material/checkbox

react-checkbox-group

react-checkbox-group is a React component for managing a group of checkboxes. It provides a simple API for handling multiple checkboxes and their states. Unlike @material/checkbox, which is a standalone Material Design component, react-checkbox-group is specifically designed for React applications and focuses on managing groups of checkboxes.

rc-checkbox

rc-checkbox is a React component for creating customizable checkboxes. It offers more flexibility in terms of styling and behavior compared to @material/checkbox. While @material/checkbox follows Material Design guidelines, rc-checkbox allows for more customization options.

react-toggle

react-toggle is a React component for creating toggle switches, which can be used as an alternative to checkboxes. It provides a different UI/UX compared to @material/checkbox but serves a similar purpose of allowing users to make binary choices. It is more suitable for applications that prefer toggle switches over traditional checkboxes.

README

Checkboxes

Checkboxes allow the user to select one or more items from a set.

Design & API Documentation

• Material Design guidelines: Selection Controls – Checkbox
• Demo

Installation

npm install @material/checkbox

Basic Usage

We recommend using MDC Checkbox with MDC Form Field for enhancements such as label alignment, label activation of the ripple interaction effect, and RTL-awareness.

<div class="mdc-form-field">
  <div class="mdc-checkbox">
    <input type="checkbox"
           class="mdc-checkbox__native-control"
           id="checkbox-1"/>
    <div class="mdc-checkbox__background">
      <svg class="mdc-checkbox__checkmark"
           viewBox="0 0 24 24">
        <path class="mdc-checkbox__checkmark-path"
              fill="none"
              d="M1.73,12.91 8.1,19.28 22.79,4.59"/>
      </svg>
      <div class="mdc-checkbox__mixedmark"></div>
    </div>
  </div>
  <label for="checkbox-1">Checkbox 1</label>
</div>

Note: If you are using IE, you need to include a closing </path> tag if you wish to avoid console warnings.

Styles

@import "@material/form-field/mdc-form-field";
@import "@material/checkbox/mdc-checkbox";

JavaScript Instantiation

The checkbox will work without JavaScript, but you can enhance it with a ripple interaction effect by instantiating MDCCheckbox on the mdc-checkbox element. To activate the ripple effect upon interacting with the label, you must also instantiate MDCFormField on the mdc-form-field element and set the MDCCheckbox instance as its input.

import {MDCFormField} from '@material/form-field';
import {MDCCheckbox} from '@material/checkbox';

const checkbox = new MDCCheckbox(document.querySelector('.mdc-checkbox'));
const formField = new MDCFormField(document.querySelector('.mdc-form-field'));
formField.input = checkbox;

See Importing the JS component for more information on how to import JavaScript.

Variants

Disabled

Note that mdc-checkbox--disabled is necessary on the root element of CSS-only checkboxes to prevent hover states from activating. Checkboxes that use the JavaScript component do not need this class; a disabled attribute on the <input> element is sufficient.

<div class="mdc-checkbox mdc-checkbox--disabled">
  <input type="checkbox"
         id="basic-disabled-checkbox"
         class="mdc-checkbox__native-control"
         disabled />
  <div class="mdc-checkbox__background">
    <svg class="mdc-checkbox__checkmark"
         viewBox="0 0 24 24">
      <path class="mdc-checkbox__checkmark-path"
            fill="none"
            d="M1.73,12.91 8.1,19.28 22.79,4.59"/>
    </svg>
    <div class="mdc-checkbox__mixedmark"></div>
  </div>
</div>
<label for="basic-disabled-checkbox" id="basic-disabled-checkbox-label">This is my disabled checkbox</label>

Style Customization

MDC Checkbox uses MDC Theme's secondary color by default for "marked" states (i.e., checked or indeterminate).

Sass Mixins

The following mixins apply only to enabled checkboxes. It is not currently possible to customize the color of a disabled checkbox.

Mixin	Description
mdc-checkbox-container-colors($unmarked-stroke-color, $unmarked-fill-color, $marked-fill-color, $generate-keyframes)	Generates CSS classes to set and animate the stroke color and/or container fill color of a checkbox
mdc-checkbox-ink-color($color)	Sets the ink color of the checked and indeterminate icons
mdc-checkbox-focus-indicator-color($color)	Sets the color of the focus indicator

The ripple effect for the Checkbox component is styled using MDC Ripple mixins.

mdc-checkbox-container-colors($unmarked-stroke-color, $unmarked-fill-color, $marked-fill-color, $generate-keyframes)

In the unmarked state, stroke and fill color may be customized independently; in the marked state, only the fill color may be customized, and the stroke will automatically match the fill color.

All parameters are optional, and if left unspecified will use their default values.

If you plan to use CSS-only checkboxes, set $generate-keyframes to false to prevent the mixin from generating @keyframes and CSS classes used by the JavaScript component.

Caveat: Edge and CSS Variables

In browsers that fully support CSS variables, MDC Checkbox references CSS variables wherever theme properties are used. However, due to Edge's buggy CSS variable support, the background-color for .mdc-checkbox__background::before will not honor CSS variables in Edge. This means you will need to override this style manually for Edge if you alter the CSS variable for the primary color.

MDCCheckbox Properties and Methods

Property Name	Type	Description
checked	Boolean	Setter/getter for the checkbox's checked state
indeterminate	Boolean	Setter/getter for the checkbox's indeterminate state
disabled	Boolean	Setter/getter for the checkbox's disabled state
value	String	Setter/getter for the checkbox's

Usage within Web Frameworks

If you are using a JavaScript framework, such as React or Angular, you can create a Checkbox for your framework. Depending on your needs, you can use the Simple Approach: Wrapping MDC Web Vanilla Components, or the Advanced Approach: Using Foundations and Adapters. Please follow the instructions here.

MDCCheckboxAdapter

Method Signature	Description
addClass(className: string) => void	Adds a class to the root element.
removeClass(className: string) => void	Removes a class from the root element.
registerAnimationEndHandler(handler: EventListener) => void	Registers an event handler to be called when an animationend event is triggered on the root element. Note that you must account for vendor prefixes in order for this to work correctly.
deregisterAnimationEndHandler(handler: EventListener) => void	Deregisters an event handler from an animationend event listener. This will only be called with handlers that have previously been passed to registerAnimationEndHandler calls.
registerChangeHandler(handler: EventListener) => void	Registers an event handler to be called when a change event is triggered on the native control (not the root element).
deregisterChangeHandler(handler: EventListener) => void	Deregisters an event handler that was previously passed to registerChangeHandler.
getNativeControl() => HTMLInputElement?	Returns the native checkbox control, if available. Note that if this control is not available, the methods that rely on it will exit gracefully.
forceLayout() => void	Force-trigger a layout on the root element. This is needed to restart animations correctly. If you find that you do not need to do this, you can simply make it a no-op.
isAttachedToDOM() => boolean	Returns true if the component is currently attached to the DOM, false otherwise.

MDCCheckboxFoundation

Method Signature	Description
isChecked() => boolean	Returns whether or not the underlying input is checked. Returns false when no input is available.
setChecked(checked: boolean) => void	Updates the checked property on the underlying input. Does nothing when the underlying input is not present.
isIndeterminate() => boolean	Returns whether or not the underlying input is indeterminate. Returns false when no input is available.
setIndeterminate(indeterminate: boolean) => void	Updates the indeterminate property on the underlying input. Does nothing when the underlying input is not present.
isDisabled() => boolean	Returns whether or not the underlying input is disabled. Returns false when no input is available.
setDisabled(disabled: boolean) => void	Updates the disabled property on the underlying input. Does nothing when the underlying input is not present.
getValue() => string	Returns the value of MDCCheckboxAdapter.getNativeControl().value. Returns null if getNativeControl() does not return an object.
setValue(value: string) => void	Sets the value of adapter.getNativeControl().value. Does nothing if getNativeControl() does not return an object.